3D Graphics Programming with QuickDraw 3D 1.5.4

Transforming Points and Vectors

QuickDraw 3D provides routines that you can use to multiply a point or vector by a matrix, thereby applying a transform to that point or vector. QuickDraw 3D also provides routines that you can use to apply a transform to each point in an array of points.

Q3Vector2D_Transform

You can use the Q3Vector2D_Transform function to apply a transform to a two-dimensional vector.



 
TQ3Vector2D *Q3Vector2D_Transform (

                     const TQ3Vector2D *vector2D, 

                     const TQ3Matrix3x3 *matrix3x3, 

                     TQ3Vector2D *result);

vector2D: A two-dimensional vector.
matrix3x3: A 3-by-3 matrix.
result: On exit, the vector that is the result of multiplying vector2D by matrix3x3 .

DESCRIPTION

The Q3Vector2D_Transform function returns, as its function result and in the result parameter, the vector that is the result of multiplying the vector vector2D by the matrix transform matrix3x3 . Note that on entry the result parameter can be the same as the vector2D parameter.

Q3Vector3D_Transform

You can use the Q3Vector3D_Transform function to apply a transform to a three-dimensional vector.



 
TQ3Vector3D *Q3Vector3D_Transform (

                     const TQ3Vector3D *vector3D, 

                     const TQ3Matrix4x4 *matrix4x4, 

                     TQ3Vector3D *result);

vector3D: A three-dimensional vector.
matrix4x4: A 4-by-4 matrix.
result: On exit, the vector that is the result of multiplying vector3D by matrix4x4 .

DESCRIPTION

The Q3Vector3D_Transform function returns, as its function result and in the result parameter, the vector that is the result of multiplying the vector vector3D by the matrix transform matrix4x4 . Note that on entry the result parameter can be the same as the vector3D parameter.

Q3Point2D_Transform

You can use the Q3Point2D_Transform function to apply a transform to a two-dimensional point.



 
TQ3Point2D *Q3Point2D_Transform (

                     const TQ3Point2D *point2D, 

                     const TQ3Matrix3x3 *matrix3x3, 

                     TQ3Point2D *result);

point2D: A two-dimensional point.
matrix3x3: A 3-by-3 matrix.
result: On exit, the point that is the result of multiplying point2D by matrix3x3 .

DESCRIPTION

The Q3Point2D_Transform function returns, as its function result and in the result parameter, the point that is the result of multiplying the point point2D by the matrix transform matrix3x3 . Note that on entry the result parameter can be the same as the point2D parameter.

Q3Param2D_Transform

You can use the Q3Param2D_Transform function to apply a transform to a two-dimensional parametric point.



 
TQ3Param2D *Q3Param2D_Transform (

                     const TQ3Param2D *param2D, 

                     const TQ3Matrix3x3 *matrix3x3, 

                     TQ3Param2D *result);

param2D: A two-dimensional parametric point.
matrix3x3: A 3-by-3 matrix.
result: On exit, the point that is the result of multiplying param2D by matrix3x3 .

DESCRIPTION

The Q3Param2D_Transform function returns, as its function result and in the result parameter, the parametric point that is the result of multiplying the parametric point param2D by the matrix transform matrix3x3 . Note that on entry the result parameter can be the same as the param2D parameter.

Q3Point3D_Transform

You can use the Q3Point3D_Transform function to apply a transform to a three-dimensional point.



 
TQ3Point3D *Q3Point3D_Transform (

                     const TQ3Point3D *point3D, 

                     const TQ3Matrix4x4 *matrix4x4, 

                     TQ3Point3D *result);

point3D: A three-dimensional point.
matrix4x4: A 4-by-4 matrix.
result: On exit, the point that is the result of multiplying point3D by matrix4x4 .

DESCRIPTION

The Q3Point3D_Transform function returns, as its function result and in the result parameter, the point that is the result of multiplying the point point3D by the matrix transform matrix4x4 . Note that on entry the result parameter can be the same as the point3D parameter.

Q3RationalPoint4D_Transform

You can use the Q3RationalPoint4D_Transform function to apply a transform to a four-dimensional rational point.



 
TQ3RationalPoint4D *Q3RationalPoint4D_Transform (

                     const TQ3RationalPoint4D *point4D, 

                     const TQ3Matrix4x4 *matrix4x4, 

                     TQ3RationalPoint4D *result);

point4D: A four-dimensional point.
matrix4x4: A 4-by-4 matrix.
result: On exit, the point that is the result of multiplying point4D by matrix4x4 .

DESCRIPTION

The Q3RationalPoint4D_Transform function returns, as its function result and in the result parameter, the point that is the result of multiplying the rational point point4D by the matrix transform matrix4x4 . Note that on entry the result parameter can be the same as the point4D parameter.

Q3Point3D_To3DTransformArray

You can use the Q3Point3D_To3DTransformArray function to apply a transform to each point in an array of three-dimensional points.



 
TQ3Status Q3Point3D_To3DTransformArray (

                     const TQ3Point3D *inVertex, 

                     const TQ3Matrix4x4 *matrix, 

                     TQ3Point3D *outVertex, 

                     long numVertices, 

                     unsigned long inStructSize, 

                     unsigned long outStructSize);

inVertex: A pointer to an array of three-dimensional points. This is the source array.
matrix: A 4-by-4 matrix.
outVertex: A pointer to an array of three-dimensional points. This is the destination array.
numVertices: The number of vertices.
inStructSize: The size of an element in the source array. Effectively, this is the distance, in bytes, between successive points in the source array.
outStructSize: The size of an element in the destination array. Effectively, this is the distance, in bytes, between successive points in the destination array.

DESCRIPTION

The Q3Point3D_To3DTransformArray function returns, in the outVertex parameter, an array of three-dimensional points, each of which is the result of multiplying a point in the inVertex array by the matrix transform matrix . The outVertex array contains the same number of points (that is, vertices) as the inVertex array, as specified by the numVertices parameter. The inStructSize and outStructSize parameters specify the sizes of an element in the inVertex and outVertex arrays, respectively.

Q3Point3D_To4DTransformArray

You can use the Q3Point3D_To4DTransformArray function to apply a transform to each point in an array of three-dimensional points, while changing the dimension of each point from three to four dimensions.



 
TQ3Status Q3Point3D_To4DTransformArray (

                     const TQ3Point3D *inVertex, 

                     const TQ3Matrix4x4 *matrix, 

                     TQ3RationalPoint4D *outVertex, 

                     long numVertices, 

                     unsigned long inStructSize, 

                     unsigned long outStructSize);

inVertex: A pointer to an array of three-dimensional points. This is the source array.
matrix: A 4-by-4 matrix.
outVertex: A pointer to an array of four-dimensional points. This is the destination array.
numVertices: The number of vertices.
inStructSize: The size of an element in the source array. Effectively, this is the distance, in bytes, between successive points in the source array.
outStructSize: The size of an element in the destination array. Effectively, this is the distance, in bytes, between successive points in the destination array.

DESCRIPTION

The Q3Point3D_To4DTransformArray function returns, in the outVertex parameter, an array of four-dimensional points, each of which is the result of changing the dimensionality of a point in the inVertex array from three to four and multiplying by the matrix transform matrix . The outVertex array contains the same number of points (that is, vertices) as the inVertex array, as specified by the numVertices parameter. The inStructSize and outStructSize parameters specify the sizes of an element in the inVertex and outVertex arrays, respectively.

Q3RationalPoint4D_To4DTransformArray

You can use the Q3RationalPoint4D_To4DTransformArray function to apply a transform to each point in an array of four-dimensional points.



 
TQ3Status Q3RationalPoint4D_To4DTransformArray (

                     const TQ3RationalPoint4D *inVertex, 

                     const TQ3Matrix4x4 *matrix, 

                     TQ3RationalPoint4D *outVertex, 

                     long numVertices, 

                     unsigned long inStructSize, 

                     unsigned long outStructSize);

inVertex: A pointer to an array of four-dimensional points. This is the source array.
matrix: A 4-by-4 matrix.
outVertex: A pointer to an array of four-dimensional points. This is the destination array.
numVertices: The number of vertices.
inStructSize: The size of an element in the source array. Effectively, this is the distance, in bytes, between successive points in the source array.
outStructSize: The size of an element in the destination array. Effectively, this is the distance, in bytes, between successive points in the destination array.

DESCRIPTION

The Q3RationalPoint4D_To4DTransformArray function returns, in the outVertex parameter, an array of four-dimensional points, each of which is the result of multiplying a point in the inVertex array by the matrix transform matrix . The outVertex array contains the same number of points (that is, vertices) as the inVertex array, as specified by the numVertices parameter. The inStructSize and outStructSize parameters specify the sizes of an element in the inVertex and outVertex arrays, respectively.